home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / tcl / extend / man / Keylist.3 < prev    next >
Encoding:
Text File  |  1993-10-26  |  4.8 KB  |  163 lines  |  [TEXT/MPS ]

  1. .\"
  2. .\" Keylist.man
  3. .\"
  4. .\" Extended Tcl binary file search command.
  5. .\"----------------------------------------------------------------------------
  6. .\" Copyright 1992-1993 Karl Lehenbauer and Mark Diekhans.
  7. .\"
  8. .\" Permission to use, copy, modify, and distribute this software and its
  9. .\" documentation for any purpose and without fee is hereby granted, provided
  10. .\" that the above copyright notice appear in all copies.  Karl Lehenbauer and
  11. .\" Mark Diekhans make no representations about the suitability of this
  12. .\" software for any purpose.  It is provided "as is" without express or
  13. .\" implied warranty.
  14. .\"----------------------------------------------------------------------------
  15. .\" $Id: Keylist.3,v 2.1 1993/07/20 08:35:45 markd Exp $
  16. .\"----------------------------------------------------------------------------
  17. .\"
  18. .TH "Tcl_GetKeyedListKeys" TCL "" "Tcl"
  19. .ad b
  20. .SH NAME
  21. Tcl_GetKeyedListKeys, Tcl_GetKeyedListField, Tcl_SetKeyedListField, Tcl_DeleteKeyedListField - Keyed list management routines.
  22. .SH SYNOPSIS
  23. .PP
  24. .nf
  25. .ft CW
  26. #include <tclExtend.h>
  27.  
  28. int
  29. Tcl_GetKeyedListKeys (Tcl_Interp  *interp,
  30.                       const char  *subFieldName,
  31.                       const char  *keyedList,
  32.                       int         *keyesArgcPtr,
  33.                       char      ***keyesArgvPtr);
  34.  
  35. int
  36. Tcl_GetKeyedListField (Tcl_Interp  *interp,
  37.                        const char  *fieldName,
  38.                        const char  *keyedList,
  39.                        char       **fieldValuePtr);
  40.  
  41. char *
  42. Tcl_SetKeyedListField (Tcl_Interp  *interp,
  43.                        const char  *fieldName,
  44.                        const char  *fieldvalue,
  45.                        const char  *keyedList);
  46.  
  47. char *
  48. Tcl_DeleteKeyedListField (Tcl_Interp  *interp,
  49.                           const char  *fieldName,
  50.                           const char  *keyedList);
  51. .ft R
  52. .fi
  53. '
  54. .SH DESCRIPTION
  55. .PP
  56. These routines perform operations on keyed lists.  See the \fIExtended Tcl\fR 
  57. man page for a description of keyed lists.
  58. '
  59. .SS Tcl_GetKeyedListKeys
  60. .PP
  61. Retrieve a list of keyes from a keyed list.  The list is walked rather
  62. than converted to a argv for increased performance.
  63. .PP
  64. Parameters:
  65. .RS 2
  66. \fBo \fIinterp\fR - Error message will be return in result if there is an
  67. error.
  68. .br
  69. \fBo subFieldName\fR - If "" or NULL, then the keys are retreved for
  70. the top level of the list.  If specified, it is name of the field who's
  71. subfield keys are to be retrieve.
  72. .br
  73. \fBo \fIkeyedList\fR - The list to search for the field.
  74. .br
  75. \fBo \fIkeyesArgcPtr\fR - The number of keys in the keyed list is returned
  76. here.
  77. .br
  78. \fBo \fIkeyesArgvPtr\fR - An argv containing the key names.  It is dynamically
  79. allocated, containing both the array and the strings. A single call
  80. to ckfree will release it.
  81. .RE
  82. .PP
  83. Returns:
  84. .RS 2
  85. TCL_OK if a list of keys is returned, TCL_BREAK if the field was not found, or
  86. TCL_ERROR if an error occured.
  87. .RE
  88. '
  89. .SS Tcl_GetKeyedListField
  90. .PP
  91. Retrieve a field value from a keyed list.  The list is walked rather than
  92. converted to a argv for increased performance.  This if the name contains
  93. sub-fields, this function recursive.
  94. .PP
  95. Parameters:
  96. .RS 2
  97. \fBo \fIinterp\fR - Error message will be return in result if there is an
  98. error.
  99. .br
  100. \fBo \fIfieldName\fR - The name of the field to extract.  Will recusively
  101. process sub-field names seperated by `.'.
  102. .br
  103. \fBo \fIkeyedList\fR - The list to search for the field.
  104. .br
  105. \fBo \fIfieldValuePtr\fR - If the field is found, a pointer to a dynamicly
  106. allocated string containing the value is returned here.  If NULL is
  107. specified, then only the presence of the field is validated, the
  108. value is not returned.
  109. .RE
  110. .PP
  111. Returns:
  112. .RS 2
  113. TCL_OK if the field was found,  TCL_BREAK if the field was not found or
  114. TCL_ERROR if an error occured.
  115. .RE
  116. '
  117. .SS Tcl_SetKeyedListField
  118. .PP
  119. Set a field value in keyed list.
  120. .PP
  121. Parameters:
  122. .RS 2
  123. \fBo \fIinterp\fR - Error message will be return in result if there is an
  124. error.
  125. .br
  126. \fBo \fIfieldName\fR - The name of the field to extract.  Will recusively
  127. process sub-field names seperated by `.'.
  128. .br
  129. \fBo \fIfieldValue\fR - The value to set for the field.
  130. .br
  131. \fBo \fIkeyedList\fR - The keyed list to set a field value in, may be an
  132. NULL or an empty list to create a new keyed list.
  133. .RE
  134. .PP
  135. Returns:
  136. .RS 2
  137. A pointer to a dynamically allocated string, or NULL if an error
  138. occured.
  139. .RE
  140. '
  141. .SS Tcl_DeleteKeyedListField
  142. .PP
  143. Delete a field value in keyed list.
  144. .PP
  145. Parameters:
  146. .RS 2
  147. \fBo \fIinterp\fR - Error message will be return in result if there is an
  148. error.
  149. .br
  150. \fBo \fIfieldName\fR - The name of the field to extract.  Will recusively
  151. process sub-field names seperated by `.'.
  152. .br
  153. \fBo \fIfieldValue\fR - The value to set for the field.
  154. .br
  155. \fBo \fIkeyedList\fR - The keyed list to delete the field from.
  156. .RE
  157. .PP
  158. Returns:
  159. .RS 2
  160. A pointer to a dynamically allocated string containing the new list, or
  161. NULL if an error occured.
  162. .RE
  163.